<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<!-- HTML file produced from file: manual.tex --
 -- using Hyperlatex v 2.3.1 (c) Otfried Cheong--
 -- on Emacs 21.4 (patch 12) "Portable Code" XEmacs Lucid, Wed Jun  2 18:57:11 2004 -->
<HEAD>
<TITLE>Scheme 48 Manual -- Interacting with the Scheme heap</TITLE>

</HEAD><BODY BGCOLOR="#ffffff">
<EM>Scheme 48 Manual</EM> | <A HREF="s48manual.html#top_node">Contents</A> | In Chapter: <A HREF="s48manual_65.html">Mixing Scheme 48 and C</A><BR>Previous: <A HREF="s48manual_74.html">Interacting with the Scheme heap</A> | Next: <A HREF="s48manual_74.html">Interacting with the Scheme heap</A>
<H2>Interacting with the Scheme heap</H2>


<P>Scheme&nbsp;48 uses a copying, precise garbage collector.
Any procedure that allocates objects within the Scheme&nbsp;48 heap may trigger
 a garbage collection.
Variables bound to values in the Scheme&nbsp;48 heap need to be registered with
 the garbage collector so that the value will be retained and so that the
 variables will be updated if the garbage collector moves the object.
The garbage collector has no facility for updating pointers to the interiors
 of objects, so such pointers, for example the ones returned by
 <CODE>EXTRACT_STRING</CODE>, will likely become invalid when a garbage collection
 occurs.
<P><H3><A NAME="1">Registering objects with the GC</A></H3>

<P>A set of macros are used to manage the registration of local variables with the
 garbage collector.
<P><UL><LI><CODE>S48_DECLARE_GC_PROTECT(<I>n</I>)</CODE>
<LI><CODE>void S48_GC_PROTECT_<I>n</I>(s48_value<I><sub>1</sub></I>, <I>...</I>, s48_value<I><sub>n</sub></I>)</CODE>
<LI><CODE>void S48_GC_UNPROTECT()</CODE>
</UL>
<P><CODE>S48_DECLARE_GC_PROTECT(<I>n</I>)</CODE>, where  <I>1 &lt;= n &lt;= 9</I>, allocates
 storage for registering <I>n</I> variables.
At most one use of <CODE>S48_DECLARE_GC_PROTECT</CODE> may occur in a
 block.
<CODE>S48_GC_PROTECT_<I>n</I>(<I>v<sub>1</sub></I>, <I>...</I>, <I>v<sub>n</sub></I>)</CODE> registers the
 <I>n</I> variables (l-values) with the garbage collector.
It must be within scope of a <CODE>S48_DECLARE_GC_PROTECT(<I>n</I>)</CODE>
 and be before any code which can cause a GC.
<CODE>S48_GC_UNPROTECT</CODE> removes the block's protected variables from
 the garbage collector's list.
It must be called at the end of the block after 
  any code which may cause a garbage collection.
Omitting any of the three may cause serious and
 hard-to-debug problems.
Notably, the garbage collector may relocate an object and
 invalidate <CODE>s48_value</CODE> variables which are not protected.
<P>A <CODE>gc-protection-mismatch</CODE> exception is raised if, when a C
 procedure returns to Scheme, the calls
 to <CODE>S48_GC_PROTECT()</CODE> have not been matched by an equal number of
 calls to <CODE>S48_GC_UNPROTECT()</CODE>.
<P>Global variables may also be registered with the garbage collector.
<P><UL><LI><CODE>void S48_GC_PROTECT_GLOBAL(<CODE><I>value</I></CODE>)</CODE>
</UL>
<P><CODE>S48_GC_PROTECT_GLOBAL</CODE> permanently registers the
  variable <CODE><I>value</I></CODE> (an l-value) with the garbage collector.
There is no way to unregister the variable.
<P><H3><A NAME="2">Keeping C data structures in the Scheme heap</A></H3>

<P>C data structures can be kept in the Scheme heap by embedding them
 inside byte vectors.
The following macros can be used to create and access embedded C objects.
<P><UL><LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
<tr> <td><CODE>s48_value S48_MAKE_VALUE(type)</CODE></td> <td align=right>(may GC)</td></tr></table>
<LI><CODE>type      S48_EXTRACT_VALUE(s48_value, type)</CODE>
<LI><CODE>type *    S48_EXTRACT_VALUE_POINTER(s48_value, type)</CODE>
<LI><CODE>void      S48_SET_VALUE(s48_value, type, value)</CODE>
</UL>
<P><CODE>S48_MAKE_VALUE</CODE> makes a byte vector large enough to hold an object
 whose type is <CODE><I>type</I></CODE>.
<CODE>S48_EXTRACT_VALUE</CODE> returns the contents of a byte vector cast to
 <CODE><I>type</I></CODE>, and <CODE>S48_EXTRACT_VALUE_POINTER</CODE> returns a pointer
 to the contents of the byte vector.
The value returned by <CODE>S48_EXTRACT_VALUE_POINTER</CODE> is valid only until
 the next garbage collection.
<P><CODE>S48_SET_VALUE</CODE> stores <CODE>value</CODE> into the byte vector.
<P><H3><A NAME="3">C code and heap images</A></H3>

<P>Scheme&nbsp;48 uses dumped heap images to restore a previous system state.
The Scheme&nbsp;48 heap is written into a file in a machine-independent and
 operating-system-independent format.
The procedures described above may be used to create objects in the
 Scheme heap that contain information specific to the current
 machine, operating system, or process.
A heap image containing such objects may not work correctly
 when resumed.
<P>To address this problem, a record type may be given a `resumer'
 procedure.
On startup, the resumer procedure for a type is applied to each record of
 that type in the image being restarted.
This procedure can update the record in a manner appropriate to
 the machine, operating system, or process used to resume the
 image.
<P><UL><LI><CODE>(define-record-resumer<I>&nbsp;record-type&nbsp;procedure</I>)</CODE><A NAME="4">&nbsp;</A>
</UL>
<P><CODE>Define-record-resumer</CODE> defines <CODE><I>procedure</I></CODE>,
 which should accept one argument, to be the resumer for
 <I>record-type</I>.
The order in which resumer procedures are called is not specified.
<P>The <CODE><I>procedure</I></CODE> argument to <CODE>define-record-resumer</CODE> may
 be <CODE>#f</CODE>, in which case records of the given type are
 not written out in heap images.
When writing a heap image any reference to such a record is replaced by
 the value of the record's first field, and an exception is raised
 after the image is written.
<P><P>
  
Previous: <A HREF="s48manual_74.html">Interacting with the Scheme heap</A> | Next: <A HREF="s48manual_74.html">Interacting with the Scheme heap</A></BODY></HTML>
